On Apr 5, 2007, at 5:51 PM, Digant C Kasundra wrote:
> I think some conventions are in order to help with the
> documentation work.
>
> (1) As suggested by someone else earlier, I think we need a clear
> way to
> mark areas needing fixes with FIXMEs.
Is it sufficient to file bugs against documentation, or should we
actually modify the document itself?
I tend to think we should use the ticketing system to indicate a need
for fixes; otherwise, we have to trawl all of the docs looking for
these ''fixme'' markups.
> (2) Topics under discussion or drafting should indicate such,
> perhaps at
> the top of the document, with a reference to the thread. On page
> comments
> should have a clearly designated area at the bottom of the page.
I agree on both of these counts -- we should clearly mark the
difference between a document draft and a final document. I''m fine
with David''s suggestion about having ''(Draft)'' in the
title, although
it''s probably sufficient to just tag it with ''draft''.
We should
definitely store a link on the docs page to a query for all docs
tagged with ''draft'', so people will know what to work on.
Now that I think about it, maybe we can skip the ticketing system and
mark the docs that need fixing in some way -- FIXME tags or whatever,
probably at the bottom -- and then tag them with ''docfix'' or
''fixme''
or something, and once again store a link to that query, so it''s easy
to find which docs are in need of fixing.
> (3) Others?
I think all documents need to store a version number for which
they''re valid. Most docs will be valid across most versions, but
we''re going to continue having trouble keeping our docs up to date
(and telling our users which version the docs are valid for) unless
we start making the doc/version linkage explicit.
We also need to start specifying when some functionality was added in
a recent release. E.g., the ''generate'' function is only
available in
0.22.2+, but people on Debian stable are still using 0.18.4 yet see
that function listed in the function reference.
I also think we''re going to quickly find that a flat doc space is not
sufficient. Our nav bar is already more than one page in length. We
should at least start talking about how to organize them -- I''d
prefer to use tag-based queries rather than a strict hierarchy, but
that means we need to have a fixed tag cloud, with the nav bar
linking to the different tagged categories, along with maybe some
extra macros for delving more deeply or something.
--
I have an answering machine in my car. It says, "I''m home now.
But
leave a message and I''ll call when I''m out. -- Stephen
Wright
---------------------------------------------------------------------
Luke Kanies | http://reductivelabs.com | http://madstop.com