Re: Documenting Packages for Future Developers

On Sun, Jan 4, 2009 at 12:38 AM, George L wrote:

> Hi all,
>
> I have a large number of custom products and eggs that I have made for a
> Plone web site project that I am now documenting. Because eventually I will
> not be around to maintain the software, I am working to make it as clear as
> possible to the next tech people how to maintain the software and make
> changes small and big. I am sharing my thinking on this to get feedback and
> because it may be helpful to other people.
>
> Much of the documentation I have seen before falls under "Learn about how
> to
> create a product." The major perspective informing my documentation work
> right now is "Learn how to understand an existing product and be able to
> make some changes to it ... including how to know what exactly about
> Plone/Zope you need to learn in order to understand the product, without
> having to learn everything!"
>
> As an example, one product I use has documentation that says its code uses
> the following techniques:
> - Standard product coding and file structure
> - Standard Plone installation, including GenericSetup
> - Install a specific tool or utility within a site: Zope2 tool in site
> root,
> registered as a Zope3 utility
> - Adding property sheets
> - Code-level techniques: custom exceptions, helper classes and methods
> - Zope3 coding techniques: including Zope3 utilities
>
> I don't bother explaining in that product's documentation all the details
> of
> what coding for a standard Plone installation looks like, what property
> sheets are, or what a Zope3 utility is -- that's where a developer can go
> learn more if they don't already know. I try to strike a balance here.
> Someone might look at this and scoff and say, "What? Any real Plone
> developer should know what property sheets are," or "Any real Plone
> developer should know how to use Zope3 utilities." But to me it seems that
> the number of Plone developers out there who know all the different
> techniques isn't huge, and it took me a long time to learn these
> techniques.
> So without dumbing down the documentation to explain every detail, the
> documentation at least gives a general overview of some of the major
> techniques someone needs to know to understand the code.
>

Are you saying you're explaining how plone works in your products? Why don't
you just link existing documentation?


>
> So tada -- this is my general comprehensive list right now of techniques
> which I draw these shorter bullet points from. Almost every line of code in
> my product is captured somewhere in this list. It would be great to hear
> feedback on using a list like this, and what people think about this list
> in
> particular.
>
> [... long list ...]
>

Like Veda has already pointed out, this is very interesting material to help
us organizing plone.org manuals and quickstarts.

Regarding the inclusion of a list of neccessary knowledge to understand how
the product works, I think this can only help, but could be time-consuming
for the developer and too rigid. Maybe describing what's the purpose of the
product and linking documentation where neccessary would have a similar
effect, e.g.:

"""
This product creates two new content-types, FortuneCookie and FortuneSteak.
For more info about content-types, check http://plone.org/docs/content-types
.
"""

"""
This product adds a new (zope 3) view to the News Item content-type using
GenericSetup. For more info about z3 view, see http://... and for more info
about GS, see http://...
"""

However, searching appropiate keywords in Google should work for most
readers, too. :-)

-- israel

------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs