Talk:Documentation Blueprint

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

Here is some documentation that NPS has been able to do. Media:GettingStarted.pdf Joseph.brower

Here is some 2 cents about that pdf :-
  • The template does not seem to have a table of contents / numbering strategy so that makes it hard to tell students to go to section N .. and
  • The screen shots are all with text beside them which only works for the log-on screen because everything else needs to be shown the full width of the page or it is unreadable (too small or missing part of the screen) - Red1 01:18, 23 July 2008 (EDT)
    • The Table of Contents can't be produced yet since the content hasn't reached critical mass. Joseph.brower
    • The screenshots are using callouts because using a full screen capture will often cause the user to become confused by flooding them with visual information. Using callouts provides better focus. The full screen captures was a major problem with the Compiere Manual. Joseph.brower
      • I dont find it confusing. What i dislike about Compiere's manual is the absence of more helpful contextual comments for newbies. - Red1 20:38, 28 July 2008 (EDT)
        • While some might not find it confusing, we must think of the target audience. When I first saw the Compiere documentation, I wondered why people would buy it. It nearly scared me away from Compiere and ADempiere. Luckily there was a community to help me get beyond my initial fear. Having a manual written by developers will likely scare future users because most users don't think like developers. We need to ensure that the documents increase user enthusiasm. Scrolling up and down a bunch because full screen captures were used will cause people to get frustrated because they'll constantly have to refer back to an image to find their place. By using callouts, that is greatly reduced, if not completely eliminated. Joseph.brower
        • Thats right. Define the target audience from the mass, define the scope too. Cos we have lots of types of docs. Even Pelgrim just did an index to help sort that. Nevertheless i think i got wind of the scope been defined or differnetiated so far somewhat in the SF discussion [1]. If this is more written out into a simple roadmap at the wiki topic here, i.e. as a Starter's Manual targeting a DIY market etc. In that light, the edited PDF looks better to me now :) - Red1 21:29, 28 July 2008 (EDT)
          • The document that the team here in Idaho is working on is meant for the nontechnical end user. We'll later be writing a technical manual that will cover customizations and such. Joseph.brower

Sample Document Blueprint

  • We can refer to many sample done even the Compiere manual that has full screens that i feel is important. Blowups can be done after that such as what i did in my own tutorials. Here i uploaded from Adaxa a sample that shows How To handle Foreign Currency Payments Adaxa Sample - Red1 20:37, 28 July 2008 (EDT)

We have prepared a template for the documentation project. The purpose of this template is to go beyond the sample Stephen created earlier in the summer. The sample setup a general design that the ADempiere community approved. However, Stephen's sample did not give the specifications necessary for uniform document design and layout. The template linked here is not intended to be a document for the manual or even a sample document. It is intended to show the other technical writers the specifics need for uniformity and time savings. Along with the template is a record of the specifications for the project: font style, size, color values, exact placement of each element, effects, etc. The template and specifications for the project are displayed at AD_document_specs.doc http://adempiere.com/wiki/index.php/Image:AD_document_specs.doc Ch_3_partner_relations_p1.pdf http://adempiere.com/wiki/index.php/Image:Ch_3_partner_relations_p1.pdf Ch_3_partner_relations_p1_wo_red_alignment_lines.pdf http://adempiere.com/wiki/index.php/Image:Ch_3_partner_relations_p1_wo_red_alignment_lines.pdf We would very much appreciate feedback from the ADempiere community on these specifications of design and layout. Thanks, Susan Grover Grovers 22:45, 24 October 2008 (EDT) →grovers 08:42 PM, 24 Oct 2008 (GMST)