On Apr 18, 2015, at 6:48 PM, Kevin Youren <kyou...@gmail.com> wrote: > > Could you possibly have information about how many people use Fossil to > track analysis and design and the changes to analysis and design?
Given the inherently distributed nature of Fossil, there is no way one person could collect such quantitative data. I think your question is better phrased, “How can one store and use design documentation in Fossil?” Here’s how I do it: Just last week, I did some up-front design in Fossil: I wrote the code for a new command line app’s “usage” message. This didn’t really amount to “code-first development,” since a usage message is plain English prose, and the surrounding app was just a skeleton while I was writing that message. I was working out how I wanted the app to work, what its interface to the outside world would be, etc. Which is to say, I was designing the app. I didn’t commence coding the rest of the app until I was happy with the usage message. The prose description of each command line option was a “use case.” I sent that usage message out to the other interested principals for comment a few times, and incorporated their feedback before starting the actual implementation. And because I don’t do waterfall development, I did occasionally go back and change the usage message as I discovered design problems in the development phase. The point is, the original usage message guided and focused the development effort. Another way I use Fossil for design docs is that I keep a Wishlist for those projects that are under continual development. As new ideas come up, they get written up in the Wishlist. The Wishlist file is in Markdown format and so is called Wishlist.md, which lets me link to it from the Fossil wiki using its “embedded documentation” feature: http://www.fossil-scm.org/fossil/doc/trunk/www/embeddeddoc.wiki That feature lets my boss look at the Wishlist (and other key files handled the same way) in his web browser, so he doesn’t have to check the code out and muck with plain text files. This feature works with plain text, Markdown, and Fossil Wiki files. From the latter two file types, you can also link to other asset types your web browser can display: PNGs, SVGs, other HTML files, etc. SVG files are particularly useful for design documentation because a lot of design work is done with diagrams, and diagramming tools can often export to SVG. This means you can display UML diagrams, flow charts, mind maps, etc. from within an embedded Fossil doc or from the Fossil wiki. Obviously such files need to live in their native tool to allow for updates, but most people you are communicating a “finished” design to don’t need to have the ability to edit the original diagram. If the diagram needs to change after being published, just re-export an SVG, check the change in, and now everyone with a copy of the Fossil repo has the current diagram. One good place for such links is in the Fossil wiki. You might have a “Current Design” page, which links to all the text and graphical artifacts that describe the design. I don’t recommend writing the design docs in the wiki itself for the reasons given at the top of that page I linked to above. Linking out from there using embedded doc syntax is different, though, because those URL targets are versioned. One of my wiki pages makes use of that feature by linking to embedded docs on the tip of old version branches, so that I effectively have several versions of these documents, appropriately varying for each major version of the software. This same feature can work for documentation at the other end of the design cycle, too: user manuals, ChangeLogs, etc. _______________________________________________ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
