[Most Recent Entries] [Calendar View] [Friends]
Below are the 20 most recent journal entries recorded in
LiveJournal Documentation Project's LiveJournal:
- a way to specify only which document is being linked to, without making unjustified assumptions about the language and formatting preferences of readers who will follow the link.
- an efficient way to determine the preferences of a reader when they're not specified in the URL.
- efficient and correct navigation between different parts of the documentation set, once the reader's preferences have been determined.
- Users of the website will go to Part I: How to Use This Site.
- Volunteers working for LJ will go to Part II: Volunteer Activities (and also to Part III or IV if they're programmers).
- Programmers and administrators participating in the open-source LJ Server endeavor will refer regularly to Part III: LJ Server.
- Programmers working more independently on client projects will refer regularly to Part IV: Client-side programming (which will document protocols and embedding methods).
- Volunteer Center (to list the contents of Part II of the manual, plus other links important to volunteers, such as the Talent Pool)
- LJ Server Resource Center (to list the contents of Part III of the manual, and generally as a front page for open-source activities)
- Client Programming Center (to list the contents of Part IV of the manual, plus other links important to client programmers)
- I now expect to end up with quite a bit more documentation on "Volunteer Activities" than we'd originally envisioned, so that's now a separate Part of the manual.
- Looking at the titles alone should now reveal which Part of the manual will hold the answer to any particular question. (Not 100% of the time, but pretty darn close.)
| Friday, August 29th, 2003 | |
| 8:17 pm [01flux] |
A quick Question - Just for personal curiousity's sake, is there a way to bring up a list of IP addresses/recent clients used for login sessions? Any info is appreciated. Thank you! |
| Sunday, August 17th, 2003 | |
| 10:10 pm [kraig] |
Installation documentation (hrm, I tried posting this in lj_dev earlier, but it doesn't appear to have shown up. I guess this is the right community anyway.) I just got a test server set up on my home machine, but I noticed a couple of mistakes in the installation documentation. #1 - at least, I'm pretty sure it's a mistake: under the Perl module requirements, Storable isn't mentioned (although checkconfig.pl complains if you don't have it). #2 - the documentation mentions "Maintanence" tasks in several places, somebody may want to s/tanence/tenance/g. I can submit patches for these, likely, if that'd be easier. |
| Sunday, October 27th, 2002 | |
| 6:28 pm [jproulx] |
RFC: Documentation (Post 1 of 2) After a long run of no updates, I figured I'd actually post in this community… Right now, it would seem that documentation efforts in this forum have stalled. Tribelessnomad has resigned from his documentation position, and a lot of the original volunteers have left or moved on to something else. I want to pick up the documentation effort again, because now more than ever, word for LiveJournal and LiveJournal based sites is spreading. However, I'd like to choose a process to work with/in, so that work isn't duplicated further down the line. There are two basic processes that I can see us using; Tribeless's proprietary XML format or DocBook: Proprietary: As I understand Tribelessnomad's plans, he created his own XML format to mark up "guides", specific sections (chapters) of a much larger manual. His markup emulated HTML in a lot of ways, so its easy to pick up on if you can already author an HTML document. Part of his system as a whole also included means to update the documentation on site without having to constantly commit files to CVS. As I'm reading through older updates, I'm seeing that the primary benefit for having our own markup is: Mainly because we'll want to write our own XSLT in many cases. That allows us to do things like applying our own styles, or converting to BML if that's necessary. Writing XSLT to handle a generic DocBook document is beyond our means, because DocBook has way too many features.Even in this system, we'd probably convert to DocBook anyways to make use of the PDF/PS conversion. DocBook: However, what I've found with DocBook, after talking to a lot of its developers, is that there are a lot of changes that they are making and have made that facilitate customizations of their DTD and stylesheets, so that content authors can have the extra control over the final product. Even using basic CSS gives us a lot of control over the final style of the HTML document. However, one drawback I keep finding is transforming a DocBook document to a BML document. Using the BML format for end-user documentation is important for sites like DeadJournal and uJournal, because the style of the documentation will follow the schemes they've designed for their sites, essentially keeping a uniform look to their site. Also, learning DocBook is no walk in the park - its not that the subject matter is difficult, just that there is a large volume of vocabulary to learn. This is a drawback that Tribeless's system tried to overcome, by giving authors a strict set of elements and a quicker to use vocabulary; but I've always held the opinion that the authoring phase should have at least 2 people, one to write in the format they feel comfortable in writing, and another to revise the content and convert that format to DocBook. Essentially, I just want to get cracking on a manual, either using DocBook or Tribeless's (or something like it) format. Since I hope to not be alone in this endevour, I would like some feedback: Poll #70989: Documentation System Open to: all, results viewable to: all How should we set this up? View Answers Proprietary XML format DocBook format Other (If selected, please leave a comment with an explanation) |
| Friday, March 29th, 2002 | |
| 9:27 am [tribelessnomad] |
Preview of the new manual Although there aren't many Guides yet, you can now visit my goathack server to see how I intend to link them together as a manual. The Guides to Volunteer Activities (Part 2) are fully integrated into the manual, so start browsing there. In a separate Part of the manual, called "How to Use This Site", are the Guides for end users. End users might be confused or annoyed if we label those Guides as part of a manual while there are only a few of them. So I came up with a scheme for partially integrating those Guides into the manual. Volunteers who know about the manual can navigate between the Contents pages for both Parts, and from there to any of the Guides. However, from a partially integrated Guide like "Mood Icons", there are no links back to the rest of the manual. End users will normally be directed to such Guides from the Support center, and won't yet see any evidence that the Guides are part of a manual. They can easily get back to Support, and find other FAQs or Guides from there. Once we have some complete chapters, and better integration with FAQs, the Guides for end users will be fully integrated into the manual. The partial-integration capability will come in useful again when other new Parts are added to the manual. I'm fairly happy with how the pages look, but the "Contents" buttons are clunky. I intend to add some JavaScript which will hide them from most users and sync the page automatically with the drop-down boxes. I do, however, need browser compatibility reports from volunteers who are interested in testing these pages. Later I'll post in more detail about possible browser compatibility issues, but if you see something that's not being displayed correctly, please go ahead and comment. Everything is generated from XML source files, of course. I'm fine-tuning the XML-based format for Guides as I assemble the manual. This seems like as good a time as any to release an update, so there's a new DTD and updated documentation explaining how to write compliant Guides. I've also updated the manual's Progress page. It shouldn't be too long before this "manual" is available on the site. First, I need to receive compatibility reports, divide the Support Guide, and submit a patch or two. I imagine that will take a week or two, allowing time for other things. |
| Saturday, February 23rd, 2002 | |
| 1:27 pm [tribelessnomad] |
"Resources for Developers" updated Actually, I updated this last weekend, but didn't post about it at the time: Resources for Developers.It was a few months out of date, but will be updated more frequently now. It should continue to be the comprehensive list of documentation for LJ developers, until it's replaced by resource centers. It links to documents which are being moved into the manual as well as many other resources. I'll probably add links to the Goals diagram and To-Do List, too. Those aren't "documentation", exactly, but they're resources which people tend to ask for at the same time. |
| Saturday, February 9th, 2002 | |
| 9:06 am [tribelessnomad] |
URLs for documents generated from XML This post describes essential aspects of the documentation layout plan I've been working on. The complete plan will be published later. The main goal of the plan is to decide on a set of URLs which will not have to be abandoned when we introduce new output formats, multiple languages, and other improvements to the new documentation system. The key idea is this: choices like output format (HTML/DocBook/PDF/etc.) and language are user preferences, which can be specified independently of the document's subject matter. They should normally remain under the control of the person who clicks on a link, not the person who posts it. Therefore, the URL scheme should be flexible enough to allow the following: The HTTP protocol's support for content negotiation provides the framework for meeting these objectives. Apache and other web servers have built-in support for HTTP content negotiation. However, the efficiency of the Apache implementation (and perhaps others) leaves a lot to be desired in terms of flexibility and efficiency. I've attempted to devise a plan which addresses these issues by minimizing reliance on the server's built-in content negotiation features. In simplest terms, I intend to use Apache's mod_negotiation for language negotiation only, and even so, I hope in the long term to replace it with a more efficient module. Since translation of LJ documentation to other languages is not being undertaken quite yet, I'll leave the details until the complete layout proposal is ready for release. Suffice it to say, for now, that the HTTP Accept-Language header, which is typically sent by browsers with every web-page request, should be a fairly reliable indication of the user's language preference, and (questions of efficiency aside) can be handled by standard means. The negotiation of a suitable output format is more important and more difficult. The format, like the language, shouldn't normally be specified in hyperlinks, for reasons stated above. But for various reasons, the HTTP Accept header often will not represent the user's formatting preference correctly. That means, first, that we need a more "intelligent" approach to server-driven content negotiation than mod_negotiation provides, and, second, that browsers will often have to resort to specifying a format as part of the URL to get what is wanted. Furthermore, format negotiation will soon be part of every normal document request, so the need for an efficient workaround for Apache content negotiation is more urgent than in the case of language negotiation. Here's my solution. (Note that the links will take you to my goathack server, because the system isn't in place on livejournal.com yet.) When a link to a document appears outside the documentation system, it should have the canonical form moodicons can be replaced by any other document ID. /doc/find is mapped to a CGI script, which will inspect not only the HTTP Accept header but also a cookie (if present) in an attempt to guess the user's preferred output format. If the script succeeds in making a guess, it will redirect the browser to an appropriate URL such asTo summarize: links from outside the documentation system should normally specify neither a language nor a formatting preference; navigation within the documentation system will be accomplished using URLs which do specify a format (but not a language). The use of format-specific URLs for internal navigation has important advantages: it greatly reduces the work the server must do in responding to each page request after the first, and it avoids any need to repeat agent-driven negotiation when the reader moves from one document to another. Although the documentation set (manual) will be organized in a hierarchical fashion, I am proposing a flat namespace for document IDs, which will be reflected for the foreseeable future in the way simple documents (Guides, References, and Chapter outlines) are stored on disk. Note that in the query string passed to /doc/find, guide=xxxxxx could theoretically result in retrieval of the introductory Guide from a Reference, or of a Chapter outline which lists multiple Guides. If that seems unacceptable to some, the parameter name guide could be replaced by id for generality -- let me know what you think.I've described here only the aspects of the plan which are most critical to moving existing documents onto the site. The full proposal, which I haven't finished writing yet, also deals with such issues as simple vs. compound documents, rules governing document IDs, the gradual evolution of the documentation set, language preferences, whether changes to language variants must be synchronized, static and dynamic representations of a document, the hierarchy of XML-based formats, and ways to encourage the use of canonical URLs which don't specify formatting. Most of the code needed to implement this plan has yet to be written. The code already being used on my goathack server to handle /doc/find requests is a starting point. It will be posted to  lj_dev. However, so far it's mostly CGI overhead, resulting in nothing but simple redirection. It's just enough to let us start moving Guides onto the site in one format (HTML), which is how we need to begin. The code needed to guess at a user's formatting preference will be added later, as soon as other priorities allow. |
| Tuesday, January 29th, 2002 | |
| 12:49 am [tribelessnomad] |
Notes on server documentation Guidelines for planning the documentation of LJ's open-source server software were posted a few days ago. At Brad's suggestion, he and I are putting our own time into devising such a plan. Any help would be welcome! Here are some notes reflecting my current ideas on what the server documentation should include. This is not yet a complete outline, just a starting point for further discussion with Brad and anyone else who might be interested. ( Notes, in outline form ... ) |
| 12:34 am [tribelessnomad] |
Documenting the documentation system In addition to the 4 Parts of the manual previously listed, I've concluded that there should be another, describing the new XML-based documentation system. The doc system will be sufficiently independent of the rest of the site, and will require a sufficiently different skill set, that documenting it together with the perl-and-BML-based codebase doesn't make much sense. Part 5, The Documentation System, will consist mostly of References, one for each XML-based format we use. However, the first Chapter will be a set of Guides explaining the organization of the entire system. I'll update the proposal for Resource Centers accordingly, since there should be one for each Part of the manual. |
| Thursday, January 24th, 2002 | |
| 12:02 pm [tribelessnomad] |
LJ Server documentation: we need a plan! We need a plan for organizing the documentation of our open-source server software. What we need is a full outline, which can be filled in gradually to create Part III of the new Manual. Plans for other Parts of the manual are already fairly stable. Please contribute whatever ideas you have, either by commenting on this post or by posting a new entry in this journal ( lj_sysdoc).( Guidelines ... ) |
| 11:54 am [tribelessnomad] |
Progress page The Progress page for the new manual has been updated, at: http://goathack.livejournal.org:8018/doc/hIt now includes technical documentation. This page has actually been online for about a month, but I think that only Brad and a few others have seen it before now. |
| 11:36 am [tribelessnomad] |
Preparatory Notes: Customizing Your Server These are the brief instructions I e-mailed to opiummmm on Oct. 10, when he volunteered to write technical documentation on the subject of customizing an LJ server. I'm posting them here, so that I can link to them from the manual's Progress page, which I've just been updating. I believe this topic is the only part of the manual for which the current status of preparations hasn't been published before.The customization guide will have to be written from scratch. It should cover BML schemes, ljconfig.pl, system journals, and whatever else would be used to make one LJ site different from another. It shouldn't be an item-by-item description of the parameters that can be tweaked. The idea is that if I want to alter something, the guide will explain clearly where I can find the code that has to be changed, without looking in other places. So you'll need to study ljconfig.pl, etc., to make sure everything's been covered, but in the guide, you shouldn't repeat any more of the details than are necessary to say what can be found where. |
| Wednesday, January 16th, 2002 | |
| 9:37 am [tribelessnomad] |
Resource Centers The new division of the manual into Parts is meant to ensure that everyone knows immediately where to go when they need information: /doc/ (not online yet) will list all available documentation formats, as well as the contents of all Parts of the manual. However, that page is not the best place for someone to go routinely every time they need information. In any particular situation, someone should be able to go directly to the Contents for the relevant Part of the manual. And if what they need lies outside the manual, they should still find a link to it by going to the same place. Links on the home page and sidebar could lead people directly to the appropriate Resource Center, where they'll find all the document and non-document resources they need, without wading through stuff that's so unrelated it might never interest them. These Centers will not be hard to set up. I just need to create a few new webpages by adapting support/index.bml. But we need to get a substantial amount of documentation ready before each center goes online. The Volunteer Center is especially needed, so I want to see it finished first. It will list the policy documents of LiveJournal's various volunteer teams, and will also be an orientation center for new volunteers. It will include the existing Guide to Volunteer Forums, instructions for joining a volunteer team (half-finished on Aug. 3), a reconfigured set of Support Guides, and the policies of lj_userdoc, among other documents. As I mentioned in 'lj_userdoc', I've asked nilesta to organize the collection of more information, and she's already hard at work on it. Tentatively, I'm thinking the Volunteer Center can go up on the site as /org/. |
| 7:37 am [tribelessnomad] |
Parts of the LJ manual, reconsidered A very rough outline of the table of contents for our manual was posted at talkread.bml?itemid=11102650#t13608536. A division into 5 Parts was planned. I now plan to make that division a little differently: Part I. How to Use This SiteThere are basically two reasons for the changes: |
| Friday, December 7th, 2001 | |
| 4:40 am [opiummmm] |
Beginnings of a DocBook set http://goathack.livejournal.org:8006/doc/ <-- ideal doc directory http://goathack.livejournal.org:8006/doc/html/ <-- Live HTML output http://goathack.livejournal.org:8006/doc/source/ <-- all source, in XML http://goathack.livejournal.org:8006/doc/source/index.xml <-- actual DocBook XML file What's going on: We have very little documentation not actually on livejournal.com, in many different formats, in scattered places. It's been agreed that all documentation that doesn't belong on the site (90%) should go into docbook format, because docbook is widely supported, and can be used to convert documentation into other (easy to read) formats. Basically, I've picked up where people have left off. I'm trying a different approach however; Instead of using DocBook's <book> definition, it seems more appropriate to use <set>, and split off the possible content into three different docbook books (manuals, I think, are a better term): LiveJournal LiveJournal Programming LiveJournal.com (not yet commenced) The differences being: LiveJournal, the user's manual, would act more like an owner's manual for someone who's just installed LiveJournal on their server. It would cover all of the features and procedures and administration techniques available, and in doing so, explain alot of the grey areas of LiveJournal. LiveJournal Programming would be the end-all reference to...LiveJournal Programming. This is the manual that is basically half complete, content wise. LiveJournal.com would be the place to put the guides that are currently in existence. It would be the place to put something that involves LiveJournal.com, the community and business, rather than the application. Where does that fit in with the plans that are currently in place? It addresses a need expressed by Brad in the code mailing list. (link) |
| Wednesday, October 24th, 2001 | |
| 7:55 pm [bradfitz] |
Progress Dormando finished all the XML-RPC documentation so I wrote up some XSLT to convert it to a DocBook reference, then put it in the manual: http://goathack.livejournal.org:8001/doc/ The HTML output you see there is from the DSSSL stylesheets. I'd tried using the XSLT ones but all the XSLT processors were buggy in some way... but then I found GNOME's libxslt and the xsltproc that comes with it: awesome & fast! I'll be using that from now on instead of DSSSL. The Makefile in ~/doc/raw/int/protocol already uses xsltproc to generate a test output HTML file (quicker than building the whole manual). Anyway, everything you need to play with this more is in CVS and programs/files are on goathack. Next thing I'll be doing is writing some XSLT to convert ~/doc/raw/local/hardware.xml into DocBook and insert it into the Installation-specific part of the manual. (90% or so of the manual should not be tied to LiveJournal.com in any way ... anything that is actually site-specific should be in doc/raw/local/*) |
| Monday, October 15th, 2001 | |
| 5:06 am [dormando] |
lj_dev FAQ addition. "Who has write access to the LJ CVS and why?" - LiveJournal development works a lot in the same way that Linux kernel development works. Each developer has their own test systems, and write their own patches. Once they write a patch, the submit to the code mailing list for further review. If they are peer reviewed fine, and bradfitz deems the patch fine and useful, it will go into CVS. Bradfitz is the only person with write access to the LJ CVS. We do this to prevent bad or uneccessary code from going into the system. There are slightly more people who can change the code that is live on LiveJournal.com, but only do so for emergencies. |
| Sunday, October 7th, 2001 | |
| 8:40 pm [tribelessnomad] |
|
| Saturday, October 6th, 2001 | |
| 4:20 am [dormando] |
LJ Internals FAQ Draft - 1 yo, That's the second draft. I like to quantify 0. Go get it here. Read it. Comment on stuff. Needs more sections? Something unclear? Still have questions? Go for it. |
| 12:25 am [tribelessnomad] |
Priority #1 ... ... according to my earlier post, is to support updating of Guides. The following files can be copied for a start: doc/xml/lj/guide/support.xml.txt doc/xml/lj/guide/1.4.4.dtd doc/xml/lj/guide/to_bml.xsl guide/Makefile If Java, Saxon, and Make have been installed, that should be all that's needed to make an updated (and greatly expanded) version of guide/support.bml. The make command should be make support.bml since there's only one file to be made at first. Later, the make command will simply be make.Once that's been done, I need to know what the procedure will be for uploading additional documents (of which there are already many). I'd like there to be some way for me and other approved editors to upload XML documents to the livejournal.com server (via CVS?), with the make process initiated automatically. Unfortunately, I don't know in detail how to make that possible, except that I think I read that CVS commits can be made to trigger other actions. Stylesheets and Makefiles can be treated as code and submitted to the Code mailing list if that's what everyone wants, but documents (and DTDs) shouldn't have to go through the same screening process. If editors can't see the result of submitting a document in pseudo-real time, there will eventually be problems caused by botched documents going live after the submitter has gone to bed. |
| 12:00 am [tribelessnomad] |
Directory structure for the documentation system I want to store most XML files in a hierarchy like this: doc - xml - - docbook - - - 4.1.2 - - - - ent - - - ljsubset - - lj - - - cimv - - - dbschema - - - guide - - - reference - - - vocabulary ( Here's why, and what remains to be decided ... ) |
3 (37.5%)