User talk:Andreschnabel/SpecTemplate

From The Document Foundation Wiki
Jump to: navigation, search

This discussion page has some hints, what the sections of the template should contain).

For many specifications it would be sufficient to have a Summary, Current Situation and Target Situation explained. This already helps to get the idea what is going to be implemented. If people feel more details need to be added, they may jin the team and just do so.


Spec Title

Summary

Place the main objective of the specification here.


Team

  • User Experience

Name (and link to wiki-account if available) of UX experts

  • Specifications should be a combination of the user's expectations and the technical options for implementation (considering side-effects and several sourounding aspects). So input from User Experience is very important. If there is no dedicated UX expert, you might have a discussion at libreoffice-ux-advise@lists.freedesktop.org and refer to this discussion.
  • possible UX tasks for the spec:
    • Interaction design (what would the workflow for the user be?)
    • GUI suggestions (how should the GUI look like and where shoul UI elements be placed?
    • String proposals/review (correct wording is often key for users to accept the feature) for UI and help
  • Developer

Name (and link to wiki-account if available) of UX experts

  • each spec should be reviewed by at least one developer. Either someone who has experience in the affected area - or the developer who is going to implement

the spec. You may look for a developer at libreoffice@lists.freedesktop.org

  • a specification should never be written without counsel from a developer. If nobody is going / able to implement it, it is just wasted time.
  • possible developer tasks for the spec:
    • suggestions for technical implementation
    • effort estimation
    • consideration if a certain idea can be implemented at all
    • prototyping :)


  • Quality Assurance

Name (and link to wiki-account if available) of QA volunteer

  • a spec should be reviewed by someone who can verify the quality of the specification and leter test the quality of the implementation
  • you may ask for ... don't know yet
  • possible developer tasks for the spec:
    • check if spec is complete (all side effects, related tasks considered?)
    • check for inconsistencies
    • prepare test scenarios (or at least define criteria for a successful implementation)


Specification

Current Situation

Textual description of the current status - including "what is wrong at the moment". Feel free to use screen shots.

Target Situation

Textual description of the desired status - including "what do we want to implement / change". Feel free to use screen shots.

Details

Place any details here. This might include:

  • workflow description, screen shots
  • string lists for UI elements
  • default values for UI elements
  • suggestions for Help texts, tool tips etc.
  • alternative implementations (that have been discussed but will not be implemented)
  • suggested timeline of implementation


Additional Information

there are often more things to consider than the certain feature - the section is merely a checklist for what might need to b considered.


Related / Open bug reports

List of bug reports related to this specification. There should be a notice, if the bugs are going to be solved with the implementation, if they become irrelevant after implementation, if they are just related or if they are new (e.g. feature requests) created during specification writing

Related whiteboard pages

The design team has a collection of Whiteboards - "a space to refine ideas until they become real solutions to be proposed to the development." If the spec is related to any of these whiteboards, put the link here.

File Format

All changes in File Format or file handling should be documented.


Configuration

If Configuration data needs to be stored in the document or in local configuration, document how this is done (path for the config item)


Migration

If document or configuration data needs to be migrated, document how this is done - or why it is not done.


Accessibility

you should verify, that you have

  • full keyboard accesibility,
  • used colors and visual representations met the desires of visual impaired people,