Message: previous - next
Month: February 2012

Re: [trinity-devel] Publishing help files, user guides, etc.

From: Darrell Anderson <humanreadable@...>
Date: Sat, 18 Feb 2012 17:24:14 -0800 (PST)
> We would probably need a few people to make sure that
> documentation is up-to-date with what is currently in 3.5.13
> (for example, was the documentation updated when the TMenu
> search box was added?), and then to make sure it is still
> up-to-date with new changes/features from R14 on.

I believe no documentation has been updated with any of the changes made after 3.5.10. :(

I have been thinking about this process for many weeks. I believe this topic ties into our recent discussions about having a review board. The bugzilla seems to be a possible avenue to trigger reviews, but often code patches are committed to the source code without a formal bug report. How do we monitor those commits for documentation reviews?

Perhaps somebody (preferably two or more people) as part of a documentation review team. Perhaps this team reviews the GIT patch logs on a daily or weekly basis and then populates a punch list somewhere to note which documentation files need updating.

If we do something like that then we need to be serious about documentation. That is, documentation that is not updated becomes a release blocker. I've been in the tech writing business many years and if documentation is not elevated to Blocker status then you can guess what happens. :)

Currently we have no process to ensure documentation is reviewed and updated. We need a way to encourage documentation reviews.

How do folks with other software projects handle this?

> I don't yet know much about git, but would it be possible to
> have a script built in to the server so that when it comes
> time to release, and development is copied over to stable
> branch, your variable is updated in stable only? Also, would
> there be a way of having Tim's quickbuild set it in the
> nightly builds?
> If that is possible, then packagers who are using
> development would still have to set it in their own
> development branch packages, but the stable release and
> nightlies for Debian/Ubuntu would be already set.

Hmm, perhaps the easiest way is to have a short shell script update the related files with each GIT HEAD update. Anybody who downloads GIT sources would have the date and release version hard-coded into the entity file. When official tarballs are released, the same entity file is hard-coded with the same information. People who generate their own tarballs have the same data frozen from the day they downloaded the sources from GIT. A shell script at the main GIT repository is the cleanest way to go. Just update the affected entity file with every HEAD update.

Tim, I haven't yet decided where I will store those entity variables, but down the road does a shell script sound doable?