David Stutzman wrote:
Forwarding this on at Wan-Teh's request for comment by all. I was just looking to help out with keeping the publicly available info current and relevant.
Dave, and others who are interested in working on NSS documentation, I welcome with great enthusiasm your help with our documentation. To help you get started, I'd like to give you some background information and suggest a few things that you can work on. I. Location of NSS Documentation Our documentation now lives on three websites: - www.mozilla.org - developer.mozilla.org - wiki.mozilla.org www.mozilla.org is the main Mozilla website, originally used for everything. It is the original NSS doc website. You need to use CVS to check out and edit the master copies of the web pages. developer.mozilla.org is Mozilla's new developer doc website. It's a Wiki. wiki.mozilla.org is Mozilla's new website for project planning. It's also a Wiki. I'm now convinced that Wiki's advantages far outweigh its problems. I believe most of the NSS developers share this view. So we plan to write new NSS documentation on developer.mozilla.org, and we have been using wiki.mozilla.org for NSS project planning. II. Hierarchy of Documentation One specific problem of Wiki we recently ran into is that Wiki doesn't require you to have a directory hierarchy of related web pages. So if you want to extract a copy of the documentation for local (offline) browsing, you can't simply specify a filtering rule that says "get everything under this directory". It seems that people are using colons (:) to establish some sort of hierarchy among the related wiki pages. So some planning in advance to make the extraction of related wiki pages easy would be appreciated. I just wrote a memo with more information on the wiki page extraction problem and the solution we're using: http://www.mozilla.org/projects/security/pki/nss/fips/wiki-download.html. III. Some Suggested Documentation Projects There is a lot of NSS documentation work to do. Perhaps we should create an NSS documentation plan on wiki.mozilla.org. Here are some suggested projects. 3.1 Migration and Conversion to Wiki Migration of some of the NSS documentation on www.mozilla.org to developer.mozilla.org would be a good project. 3.2 Obtaining developer.netscape.com Contents Unfortunately only the NSS developers at Red Hat or Sun have access to the master copies of those files (in Framemaker format), which are Appendices of the Netscape Certificate Management System Admin Guide. An alternative approach is to just use the web pages on docs.sun.com or redhat.com, and get an approval from Red Hat or Sun to contribute them. I remember this approach was pursued but we got stalled in the "get approval" step. 3.3 Release Notes We also need to write release notes for the latest NSS releases (3.10, 3.11, and 3.11.1). If you are interested, start with the NSS Roadmap for NSS 3.11 at http://wiki.mozilla.org/NSS:Roadmap and the previous NSS release notes at http://www.mozilla.org/projects/security/pki/nss/release_notes.html. For NSS 3.x, the emphasis is on new features. For NSS 3.x.y, the emphasis is on bug fixes. Changes in NSS 3.x.y are usually few enough that you can do a Bugzilla query for bugs with target milestone 3.x.y to determine them. Changes in NSS 3.x can be determined by doing a CVS diff of the NSS public header files and the symbol export files (nss.def, smime.def, and ssl.def) to determine what new exported functions, public data types, and public macros have been added, and then cross reference with the roadmap and Bugzilla enhancement requests. 3.4 API Documentation (Programmer's Manual) Document every exported function, public data type and macro. This should use the SSL Reference as a starting point. 3.5 User's Manual Installation, compiling and linking with NSS, command line utilities, etc. Wan-Teh _______________________________________________ dev-tech-crypto mailing list dev-tech-crypto@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-tech-crypto
