MarkW, Thank you for your point of view. While I agree that it is a process of sharing between developers and users that allows us to understand the software and get properly informed to its behavior and usage. I highly disagree that esoteric technical document formats like docBook that never gained strong popularity in the word processing tools are a not a technological barrier.
If a Systems Librarian wants to write down the installation procedure for putting DSpace on Windows (on say, their blog or the dspace wiki), and it is really valuable to the community to utilize those directions, then it is prudent to get it into the documentation. You have the following choices to get it there: 1.) Make the them a commiter and hope you can get them to contribute to it in your specialized "docBook source code", in which case he needs to learn docBook, or find tools to support editing it. (Creates more work for them!) They become the bottleneck. 2.) You take his copy and reformat it yourself and add it to the documentation. (Creates More work for you!) You become the bottleneck. 3.) Put your documentation up in a popular manageable open document management tool that allows you user to contribute the documentation and have him cut/paste it out of his word processor there. (Less work for everyone) There is no bottleneck. I think its fairly obvious which is ultimately most scalable and has the lowest barrier to adoption. Likewise, if managing the Manual is in the same identical tool that the WIKI content is in... Then we have a serious WIN / WIN because as the content of the WIKI site matures it becomes candidate material for the Manual. Because they are in the same identical format (confluence) there is 0 barrier to integrating content from one source to the other. MarkD On Tue, Jan 5, 2010 at 1:54 PM, Mark H. Wood <[email protected]> wrote: > I am not so sure that technology is the highest barrier to wider > participation in documenting software. The one seemingly > insurmountable hurdle, shared by all software projects, is that only > the developers know what the software will do until they write their > knowledge down. Someone who is not developing the software can only > cross this hurdle in two ways: > > o Learn the languages, tools, and processes used to develop the > software until the source becomes readable. In other words, become > another developer. > > o Interview developers at length to extract their knowledge (the way > commercial software was documented, back when commercial software > documentation was actually usable). Hello bottleneck. > > -- > Mark H. Wood, Lead System Programmer [email protected] > Friends don't let friends publish revisable-form documents. -- Mark R. Diggory Head of U.S. Operations - @mire http://www.atmire.com - Institutional Repository Solutions http://www.togather.eu - Before getting together, get t...@ther ------------------------------------------------------------------------------ This SF.Net email is sponsored by the Verizon Developer Community Take advantage of Verizon's best-in-class app development support A streamlined, 14 day to market process makes app distribution fast and easy Join now and get one step closer to millions of Verizon customers http://p.sf.net/sfu/verizon-dev2dev _______________________________________________ Dspace-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/dspace-devel
