Linee Guida per la Documentazione

This Wiki is a collaboration effort of FrontAccounting community to document the FrontAccounting ERP application. You are always welcome to make FA documentation better. Our wiki is powered by PmWiki engine. If you are not familiar with this type of wiki or you simply want to make some tests before start feel free to use Wiki sandbox for this.

FrontAccounting wiki structure.

All content on our wiki (beside some administration pages) is available for readers without prior registration or login. To gain rights to change wiki content and add new information you have to be registered FA forum member.

Our wiki contains a couple of areas grouping pages with various content:

1. Main - is main group of pages. Feel free to add any information in current pages or create new one.
2. Help - this group of pages is used as context help in FrontAccounting application, therefore creation of new pages in this group is reserved for administration staff only. Content can be changed by all registered users.
3. Devel - contains all stuff interesting for people who want to be involved in development process, or simply are curious about the application internals. This is also the best place to announce and discuss planned FA extensions and improvements. Edition access to development area is constrained to development team and forum users in Senior Member group. If you feel you need to have edition rights in this area do not hesitate to contact forum admins to update your status regardless of your actual forum activity.

FrontAccounting wiki and forum login systems are integrated together, so you can login once in one of these areas to appear as an active user in both. Also logging out in any place will do it for both the forum and wiki.

FA wiki supports multilingual content, although english is default wiki language and should always be used in page content. You can select your preferred language by selector included in page header. If currently displayed page contains no content section for selected language, the the default one (english) is displayed.

To help create multilingual content with consistent appearance, FA wiki has set of templates used for various types of content. When you start new page, or try to edit old one which does not contain section for your preferred (currently selected) language, wiki adds content template at the end of file. Wiki templates are not editable for wiki users, so if you have any idea how to improve them, or simply you want to start new language support in FA wiki please contact administration staff.

Base edition rules

These are the broad guidelines used for writing documentation pages for FrontAccounting.

• Use simple markup for documentation. (KISS)
• Don't rely on WikiWord? links; to link to other pages use [[Wiki Word]].
• Mark incomplete pages or documents needing review with category? marker [[!Documentation To Do]] or [[!Fix me]] near a part of text needing work.
• Use http://example.com/ as the prefix for example URLs. ^[1]
• Use example names for values in code examples, like GroupName, PageName, label=Search.
• Use ->[@ or -->[@ to indent code examples.
• Place any documentation-specific styles in PmWiki:Group Header.
• Don't use table markups for things other than tables.
• Use the (:keywords:) markup to provide keywords to assist with searches.
• Indicate the intended audience and difficulty level of your documentation.
• Use headings !! and !!! to divide your page into manageable "chunks". Use "sentence capitalization" for headings (capitalize only the first letter of the heading and any proper names).
• Use "newspaper-style" writing where possible. Facts first. Story later. Punchy. (See below)
• Do not "sign" documentation unless it is a personal opinion you don't want changed.
• To ensure correct language dependent link titles over the wiki always use (:title-xx title of page:) markup for translated pages. Do not add it if the page is not translated to given language at all to not confuse other readers.

Details

Many of the quick points above need no further explanation, but the items below provide more details and "how to" information.

KISS (Keep It Short & Simple)

Keep the markup in the documentation simple. The PmWiki documentation is a self-demonstration of what can be done with wiki markup, and like any collaborative document it needs to be accessible to many authors. It's important for the markup to be readable - not just the rendered output.

How to indicate audiences and document difficulty level

Indicated audiences are not intended to be exclusive or constraining; they just provide a convenient way for a user to decide what is relevant to them. And, of course, a convenient way for authors to indicate who their docs are intended for.

• The keywords for audiences are readers, authors, admins (and all for all three)
• The keywords for difficulty levels are basic, intermediate, advanced.

There is no direct relation between the audience and the level - audience classifies the individuals accessing the wiki, while level indicates the relative difficulty of the material.

Suggested markup (near or at the top of the page):

(:Audience: readers, authors (basic):)

Suggested markup (in the page):

%audience% readers, authors (intermediate)

How to provide keywords to assist with searches

Use this markup:

Example for this page:

Add keywords before any visible content on the page.

How to make sure links work

Not every page that is in the PmWiki group here or on pmwiki.org ends up in the distribution. Beware of creating links to non-distributed pages.

• Use either [[FaWiki:Page Name]] markup for links to pages that may not be included in the FA wiki distribution.
• Don't rely on WikiWord links, use [[Wiki Word]] markup.Not every wiki has WikiWords? enabled, so when writing documentation if a WikiWord is intended to link to another page then enclose it in double brackets as [[Wiki Word]]. Not every occurrence of a WikiWord needs to be a link -- generally just the first is sufficient.

Use headings for information "chunking"

A long page of unbroken text can discourage readers. Use headings to break your page into sensible chunks. Headings allow readers to quickly find the information they are seeking.

Use "newspaper-style" writing where possible

In "newspaper-style" writing, you tell the whole story right at the start and then elaborate on the details later. This allows readers to get a quick appreciation of the subject at hand - and for many, that will be enough. Anyone looking for more discussion or examples reads further to find them. In newspapers, the whole story is usually told in the first paragraph. Newspapers use short sentences. The sentences are "punchy".

Do not "sign" documentation

FA wiki makes it very easy to "sign" your contributions by inserting ~~~ in the edit window. Signing is appropriate when you are posing questions or expressing a personal opinion. Most authors are very reluctant to edit signed material. However, documentation generally is not a personal opinion, and editing should be encouraged. The curious can use the history view to see who said what.

Some suggested text "styles"

• to indicate a file name, use "emphasized" markup.

''filename.ext'' or ''local/config.php''

• to indicate a directory name alone, use "emphasized" markup and include the trailing slash (/).

''cookbook/''

Suggested Styling for Wiki Links and Link Text

Link Text Spacing

• In general minimise the use of CamelCase, ie prefer [[Page Directives]] to [[PageDirectives]]
• When link leads to multilanguage content use [[Sales|+]] syntax to ensure translated title will be used as a link text if available.

Questo Wiki è il risultato dello sforzo collaborativo effettuato da tutta la comunità di FrontAccounting per documentare l'applicativo: chiunque abbia voglia di migliorare questo materiale è il benvenuto. Il Wiki utilizza come motore PmWiki: se non avete familiarità con questo tipo di wiki, o se desiderate semplicemente fare qualche prova prima di iniziare, potete utilizzare liberalmente l’apposita Wiki sandbox.

Struttura del Wiki di FrontAccounting

Tutto il materiale del wiki (tranne alcune pagine di amministrazione) è accessibile ai lettori, senza bisogno di registrazione o login preventivi. Per modificare i contenuti, o per aggiungervi nuove informazioni, è invece necessario registrarsi come membri del forum FA. Nel wiki le pagine sono raggruppate in aree distinte per contenuto:

1. Main – è il gruppo principale. Qui è possibile creare nuove pagine e modificare il contenuto di quelle esistenti in tutta libertà.
2. Help – questo gruppo di pagine viene utilizzato anche per l’help contestuale di FA, motivo per cui la creazione di nuove pagine in questo gruppo è riservato ai soli amministratori. Gli utenti registrati possono però modificarne il contenuto.
3. Devel – contiene materiale interessante per chi abbia intenzione di coinvolgersi nel processo di sviluppo dell’applicazione, oppure che sia semplicemente curioso di conoscerne in profondità il funzionamento. Questo è anche il luogo migliore in cui annunciare e discutere le exstension e i miglioramenti futuri. L’accesso in modifica a quest’area è riservato agli appartenenti al team di sviluppo ed ai membri senior del forum. Per essere abilitati alle modifiche, dovete rivolgervi agli amministratori del forum.

I sistemi di controllo degli accessi del forum e del wiki di FA sono integrati; per cui, effettuando il login in una di queste aree, verrete automaticamente attivati in entrambe. Analogamente, ovunque facciate logout, questo avrà effetto in entrambe le aree.

Il wiki di FA supporta la presentazione di contenuti in più lingue: per richiamare il vostro linguaggio preferito utilizzate i selettori posti in alto a destra nell’header delle pagine. Tuttavia, è l’inglese il linguaggio predefinito del wiki e tutte le pagine dovrebbero disporre di contenuti in questa lingua: qualora la pagina richiesta non contenga informazioni nel linguaggio selezionato, saranno queste informazioni in inglese ad essere visualizzate.

Per agevolare la creazione di contenuti multi-lingua con un aspetto coerente, nel wiki sono stati predisposti dei modelli per i vari tipi di contenuto. Quando iniziate a comporre una nuova pagina, o ne modificate una esistente che non contiene sezioni nella lingua da voi selezionata, il wiki aggiunge un modello per questo genere di contenuto alla fine del file. I modelli non sono modificabili dagli utenti, per cui se avete qualche idea per migliorarli, o semplicemente desiderare iniziare a scrivere pagine di supporto in una nuova lingua, contatate gli amministratori.

Regole di base per l’editazione

Di seguito sono riportate indicazioni di base per la scrittura delle pagine di documentazione.

• Nella documentazione utilizzate istruzioni di markup semplici (KISS)
• Non fate affidamento sui link WikiWord?; per navigare verso altre pagine usate l’istruzione di markup [[Wiki Word]].
• Per marcare le pagine incomplete o da rivedere, posizionate dei marcatori di categoria? [[!Documentation To Do]] oppure [[!Fix me]] vicino alla porzione di testo da ricontrollare.
• Usate http://example.com/ come prefisso per le URL del dominio example ^[2]
• Usate nomi significativi per i valori specificati negli esempi di codice, come GroupName, PageName, label=Search
• Usate ->[@ oppure -->[@ per indentare gli esempi di codice
• Collocate tutti gli stili specifici per la documentazione in PmWiki:Group Header
• Non usate le istruzioni di markup specifiche per le tabelle per elementi che non siano tabelle
• Usate l’istruzione di markup (:keywords:) per specificare parole-chiave che siano di aiuto nelle ricerche
• Indicate il pubblico di riferimento e il livello di difficoltà della vostra documentazione
• Usate gli heading !! e !!! per dividere le vostre pagine in “sezioni” più facilmente gestibili; e per le intestazioni usate il formato "sentence capitalization" (in maiuscolo la prima lettera di ogni nome)
• Usate se possibile uno stile “giornalistico": prima i fatti, poi i racconti. (vedi oltre)
• Non “firmate” la documentazione a meno che non si tratti di un’opinione personale che non volete che venga modificata.
• Per assicurare la correttezza dei titoli dei link in dipendenza della lingua, nelle pagine tradotte usate sempre l’istruzione di markup (:title-xx titolo della pagina:) . Ma, non aggiungete questa istruzione se non avete tradotto la pagina nella lingua indicata: ciò potrebbe creare confusione agli altri utenti

Dettagli

Molte delle brevi istruzioni sopra riportate non necessitano di ulteriori spiegazioni; tuttavia qui di seguito vengono forniti maggiori dettagli e informazioni riguardo al loro utilizzo.

KISS (Keep It Short & Simple)

Fate in modo che le istruzioni di markup presenti nei documenti siano il più possibile semplici: la documentazione di PmWiki è una dimostrazione di questo principio. In tutti i documenti collaborativi, alla cui stesura collaborano molti autori, più che l’effetto visivo che si ottiene è importante la comprensibilità del markup.

Come indicare il pubblico di riferimento e il livello di difficolta del documento

L’indicazione del pubblico di riferimento non deve essere inteso in modo vincolante ed esclusivo; è un modo per aiutare l’utente a decidere se l’argomento trattato sia rilevante per lui o meno, e per consentire all’autore di specificarne lo scopo.

• Le parole-chiave per il pubblico sono readers, authors, admins (e all per tutti e tre)
• Le parole-chiave per i livelli di difficoltà sono basic, intermediate, advanced

Non ci sono relazioni dirette tra pubblico e livelli – il pubblico classifica gli individui che accedono al materiale del wiki, mentre i livelli indicano il livello relativo di difficoltà del materiale.

Markup suggerito in prossimità d’inizio pagina:

(:Audience: readers, authors (basic):) 

Markup suggerito all’interno delle pagine:

%audience% readers, authors (intermediate) 

Come indicare parole-chiave per agevolare le ricerche

Usate questo markup all’inizio della pagina, prima di qualsiasi contenuto visualizzabile:

Esempio per questa pagina:

Come assicurarsi che i link funzionino

Non tutte le pagine presenti nel gruppo PmWiki, sia qui che su pmwiki.org, vengono messe in linea. Fate attenzione a non creare link verso pagine non in linea.

• Usate l’istruzione di markup [[FaWiki:Page Name]] per collegamenti a pagine che potrebbero non essere incluse nella distribuzione del wiki di FA
• Non fate affidamento sui link WikiWord, usate l’istruzione di markup [[Wiki Word]]. Le WikiWord? non sono abilitate su tutti i wiki: quindi, quando si scrive la documentazione, se è presente una WikiWord che volete che determini un link verso un'altra pagina, racchiudetela tra doppie parentesi quadre in questo modo [[Wiki Word]]. Non è necessario che ogni occorrenza della WikiWord sia anche un collegamento – in genere basta la prima

Usate gli heading per creare "sezioni"

Lunghe pagine di testo senza interruzioni possono scoraggiare la lettura. Usate gli heading per suddividere la vostra pagina in parti distinte, che consentano ai lettori di individuare meglio l’informazione che stanno cercando.

Usate uno stile “giornalistico" ovunque possibile

Nella scrittura di tipo giornalistico si riepiloga l’intera storia all’inizio, di solito nel primo paragrafo, utilizzando frasi brevi e pregnanti; solo in seguito vengono trattati i dettagli. In questo modo si consente ai lettori di comprendere rapidamente l’argomento trattato: per molti questo sarà sufficiente, mentre chi è alla ricerca di ulteriori informazioni o di esempi andrà avanti nella lettura.

Non “firmare” la documentazione

Il wiki consente di “firmare” i propri contributi inserendo la sequenza [[~mcannavo52]]~ nella finestra di editazione: la maggior parte degli autori si asterrà dal modificare il materiale “firmato”. L’apposizione della firma è una pratica appropriata nel caso si stiano ponendo delle domande o formulando delle opinioni personali. Ma la documentazione in genere non è fatta di opinioni personali, e la sua modifica va incoraggata: limitate quindi l'uso della firma. I curiosi possono utilizzare la pagina history per sapere chi ha detto cosa.

Stili di testo raccomandati

• per indicare un nome di file, usate il markup di “enfasi” che visualizza il testo interessato in formato corsivo.

''filename.ext'' or ''local/config.php''

filename.ext or local/config.php

• per indicare il solo nome di una directory, usate il markup di enfasi e includetevi la barra finale (/).

''cookbook/'' 

Stili raccomandati per Wiki Link e Link di Testo

Spaziatura dei Link di Testo

• In generale, riducete al minimo l’uso dello stile CamelCase, cioè preferite [[Page Directives]] a [[PageDirectives]]
• Quando il link rimanda a un contenuto multi-lingua usate la sintassi [[Sales|+]] per essere sicuri che come testo del link venga usato, se disponibile, il titolo tradotto