| | 1 | [http://trac.sahanapy.org/ Home] |
| | 2 | = Wiki Guidelines = |
| | 3 | == Page Standards == |
| | 4 | * At the top and bottom of each page there must be a link to the parent page in the hierachy |
| | 5 | * Below the header should be the page's title - which should match the Title used in the Link (after the parent page's name) |
| | 6 | * |
| | 7 | |
| | 8 | == Current Page Sections == |
| | 9 | |
| | 10 | === BluePrints === |
| | 11 | === Developer Guidelines === |
| | 12 | === Installation Guidelines === |
| | 13 | === Trac === |
| | 14 | === User Guideline === |
| | 15 | === Wiki === |
| | 16 | |
| | 17 | == Proposed Page Sections == |
| | 18 | === Specifications === |
| | 19 | Currently the BluePrints are a good place to collect ideas, user stories and drafting specification. However they generally lack the formality of specifications required for the development. For this reason it is proposed that Specification pages are created to support the development process. Typically the specification is NOT a technical document, and must be prepared with a non-technical audience in mind. Perhaps it would be more accurate to refer to them as "Functional Specifications". The exception is when the specification is referring to a framework component, when the "users" will be other developers.[[BR]] |
| | 20 | |
| | 21 | Joel Spolsky has good write-ups on why specifications are important and how to write them: |
| | 22 | * [http://www.joelonsoftware.com/articles/fog0000000035.html Painless Functional Specifications - Part 1: Why Bother?] |
| | 23 | * [http://www.joelonsoftware.com/articles/fog0000000036.html Painless Functional Specifications - Part 2: What's a Spec?] |
| | 24 | |
| | 25 | Although it is a BluePrints page, [BluePrintDecisionMakingTechnicalTwo] is a good example of a specification. The following template has been based on the sections from from this specification, plus a few others. |
| | 26 | |
| | 27 | ==== Specification Template ==== |
| | 28 | |
| | 29 | ===== History ===== |
| | 30 | A place to record the status and progress of the specification, especially review and approval from users/domain experts.[[BR]] |
| | 31 | yyyy-mm-dd[[BR]] |
| | 32 | <Name>[[BR]] |
| | 33 | <Review Comments> |
| | 34 | ===== Overview ===== |
| | 35 | ===== Scenarios/User Stories ===== |
| | 36 | optional |
| | 37 | ===== Non Goals ===== |
| | 38 | optional[[BR]] |
| | 39 | What the system will NOT do. |
| | 40 | ===== Definitions ===== |
| | 41 | optional[[BR]] |
| | 42 | Of any new terminology in the specification |
| | 43 | ===== Users ===== |
| | 44 | What different types of users will be using the system? What tasks will they be performing? |
| | 45 | ===== Data Model ===== |
| | 46 | A list of the tables and fields that the system will include |
| | 47 | ===== Flowcharts ===== |
| | 48 | Optional[[BR]] |
| | 49 | Showing any complex navigation between screens or flow of algorithms. |
| | 50 | ===== Menu ===== |
| | 51 | For User Modules/Applications[[BR]] |
| | 52 | A hierarchical overview of all of the screens |
| | 53 | |
| | 54 | ===== Screens ===== |
| | 55 | For User Modules/Applications[[BR]] |
| | 56 | A detailed description (preferably with wire-frames) for all of the new screen in the system. |
| | 57 | |
| | 58 | ===== API ===== |
| | 59 | For Framework Modules [[BR]] |
| | 60 | The functions and other interfaces which other developers will use to interface with the system. |
| | 61 | ===== Technologies ===== |
| | 62 | Optional[[BR]] |
| | 63 | A list of specific libraries, APIs etc which will be used by the system. NOT including the standard SahanaPy Ones. |
| | 64 | ===== References ===== |
| | 65 | Optional[[BR]] |
| | 66 | Any external resources which may support of clarify this specification. |
| | 67 | ===== Open Issues ===== |
| | 68 | Optional[[BR]] |
| | 69 | Any unresolved issues or unanswered questions concerning the system. |
| | 70 | ===== Comments ===== |
| | 71 | A sections where people are able to leave informal comments on the specification.[[BR]] |
| | 72 | |
| | 73 | Although it may be difficult to start with, as we start having more specifications documented, it will become easier to write new ones as we will have more examples to refer to. |
| | 74 | |
| | 75 | === Code Documentation === |
| | 76 | === Technical Documentation === |
| | 77 | Features between the Python Developers and End Users |
| | 78 | * Installation |
| | 79 | * Configuration |
| | 80 | * Themes (CSS?) |
| | 81 | * Menus |
| | 82 | * Web Services |
| | 83 | * Synchronization |
| | 84 | * Data Import/Export |
| | 85 | === User Documentation === |
| | 86 | How do we want to present this? |
| | 87 | === Branches === |
| | 88 | Is it worthwhile for people to document any active branches to keep track of what people are working on and what new features are being introduced into the code. Or is Launchpad sufficient? |
| | 89 | |
| | 90 | === Deployments === |
| | 91 | Where SahanaPy is being used. This should link to the appropriate Branch, but ideally not be in technical language - it should be more promotional. |
| | 92 | |
| | 93 | === Contributors === |
| | 94 | Is is worthwhile for contributors too be able to have profile pages? it would be good to have some sort of contact directory. |
| | 95 | |
| | 96 | [http://trac.sahanapy.org/ Home] |
