Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??

I wish you had been there too. That was in fact the entire conversation, and you are quite correct, the precise nature of tye's concerns were not explored, though perhaps they should have been. Hopefully, tye will add a more detailed explanation of his concerns to this thread.

I, of course, don't feel as uncomfortable with tye's decision as you do.

For one, I find the idea of mixing up site documentation with pmdev documentation very confusing. Sitedocs are end user documentation. pmdev docs are developer documentation. Different kinds of people volunteer to write them. They need different editorial styles and appeal to entirely different audiences. For decades we've been shipping applications with seperate technical and end user documentation, precisely for these reasons.

I also think you are seriously underestimating the number of nodes needed to do a good job of development documentation. If we were only talking about 4 or 5 nodes, a manually maintained faqlist would problably work well. However, I've never documented a system this complex with so few nodes. Nor have I seen any other comparable system documented well with only 4 or 5 nodes.

But even if it were true that we can fit all the documentation into 10 or so pages of solid unbroken text (640K), cramming as much as possible onto each page would hardly be advisable:

  • Editing 64K page of documentation just isn't practical. Every save brings you back to the top of the document, scrolling back down over and over again is error prone and time consuming.
  • Technical documentation benefits greatly from rich hyperlinking and hyperlinking works best when documents cover short discrete topics. If each topic has its own document, then we can link to the topic by linking to the document. If we cram topics into a page until we run out of space, then we have to do links internal to the document. These links tend to be a lot more work to set up (we have to manually add <a name="blah"> tags. They also tend to be less stable: it is all too easy to wipe them out simply by editing the document. Link rot can also happen with document ids, but it is a lot easier to write a program to find those than it is to write a problem to verify "#blah" links.
  • Crowding too much information onto a page tends to strangle the various subtopics on the page. A topic is more likely to get full detailed treatment when it has a page of its own.
  • Moving detailed topics onto their own page makes overview pages easier to scan. They can then become learning tools that give new developers a chance to see the big picture. In a complex system overview pages are especially important because they help people understand the range of things to be learned.
  • If the documentation is well organized, overview pages also help people blackbox parts of the system that they don't have time to learn. This means that someone can get up to speed on a particular part of the system without having to understand the whole.

Would you still consider a manually maintained faqlist a good way to manage documentation if we had 20,30,50,100 nodes? I would contend that we'd be spending a lot of time simply making sure all the nodes we created ended up on that list. On the other hand, if the nodes are part of a separate node type it just happens automatically. We can then spend the management time on something more useful.

You suggest that wanting new node types violates the YouArentGonnaNeedIt principle. However, that principle applies to adding features that you don't have any use for (yet). Adding new node types doesn't add new features. It reuses existing features (sitedoc infrastructure, node types, inheritance) for a new purpose. By your own admission the rationale for creating new nodetypes (permissions) is legitimate. And even if we were adding new features, we'd be adding something we'll use right away, not at some fuzzy time in the future.

Finally, in Re^3: Pmdev documentation, you suggest there is a cost to adding new nodetypes but you haven't elaborated what costs you are concerned about. It is hard to have a discussion about costs that aren't specified.

In theory, we should be able to create a set of subtypes of SiteDoclet etc and be done with it. After all, we only want to change the permissions and the Everything engine supports inheritance for all of the rest. Unfortunately, the first few htmlcode nodes I've looked at all have "SiteDocClan", "SiteDoclet", etc hardcoded throughout. This leaves us with the following options:

  1. copy all of the relevant nodes and then do a massive search and replace. This adds yet another N htmlcode etc nodes to the mix, but it may be the least disruptive)
  2. refactor the nodes with hardcoded strings. Instead derive this information from the nodetype. This would eliminate the need to copy,search,and replace. And if we ever wanted to do this again, it would save us time in the future. On the other hand, PM doesn't really have a robust test environment, so maybe copying is safer. If we break anything, at least we'll be breaking something only a few people need to use rather than a widely used production system.
  3. copy and refactor. Eliminates risk of disrupting existing systems, but still adds N new nodes that are very similar to existing nodes. On the other hand, we could use the pmdev documentation to test the refactoring and once we gained confidence we could gradually move the sitedoc to the refactored solution and get rid of the almost alike nodes.
  4. Begin documenting in sitedoc, but work on one of the above solutions. When the pmdev nodetypes are done, change the nodetypes on the documentation.

My own preference is for 3+4: temporarily using sitedocs while working on option 3 (make and refactor copy). I am concerned about the time involved in refactoring and the very slow run-debug cycle (since I can't apply patches or create a development server). On the other hand, I don't know whether even temporary residence in sitedocs would be a problem and that brings us back to the question that wasn't really discussed: how having pmdev docs mixed in with sitedocs affects search logic.

Best, beth


In reply to Re^3: Pmdev documentation by ELISHEVA
in thread Pmdev documentation by ELISHEVA

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others meditating upon the Monastery: (3)
As of 2024-03-29 07:18 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found