Documentation Of A PageWhat is a page? For a web application, single page application or old fashioned server rendered page, a page is what has a unique URL.
When documenting a page we have to document the following:
What is a page? For a web application, single page application or old fashioned server rendered page, a page is what has a unique URL.
When documenting a page we have to document the following:
Page NameEvery page has to have a unique name that is used to refer to it everywhere. The name of the page should use the Page suffix, e.g. Dashboard Page or Login Page.
Page suffix, e.g. Dashboard Page or Login Page.Overview (no heading)Overview tells you what is the purpose of the page. Who is the main user of the page, and which key journeys the page falls on. No need to list all journeys.
Also note the few key things a user wants to do when they come to this page. Only needed if the main purpose of the page is to allow multiple actions a user can take (eg a page can list tweets, and the actions user can take could be edit tweet, delete tweet, like tweet, retweet the tweet, view tweet status etc).
Overview tells you what is the purpose of the page. Who is the main user of the page, and which key journeys the page falls on. No need to list all journeys.
Also note the few key things a user wants to do when they come to this page. Only needed if the main purpose of the page is to allow multiple actions a user can take (eg a page can list tweets, and the actions user can take could be edit tweet, delete tweet, like tweet, retweet the tweet, view tweet status etc).
URL and ParametersThe URL of the page should be documented in this section.
The URL may encode for parameters, e.g. the URL /jack/ contains the username. Or /login/?next=/ contains the next parameter.
For each parameter we should specify if the parameter is a string or boolean etc. Similarly we should specify if the parameter is required. If the parameter is optional, what happens if the parameter is missing, do we fallback to some default value, or do we change the behaviour of the page? Do we carry on some validations on the parameters?
The URL of the page should be documented in this section.
The URL may encode for parameters, e.g. the URL /jack/ contains the username. Or /login/?next=/ contains the next parameter.
For each parameter we should specify if the parameter is a string or boolean etc. Similarly we should specify if the parameter is required. If the parameter is optional, what happens if the parameter is missing, do we fallback to some default value, or do we change the behaviour of the page? Do we carry on some validations on the parameters?
DesignThis heading has one or more sub-headings. Right after the heading Design, it should show the screenshot of the page. This is the representative image.
Design, it should show the screenshot of the page. This is the representative image.Page Component DocumentationIn order to explain different components of the page, multiple sub headings may be used. Subheadings for components of the page should start with “Component: ” or somehow indicate this is a page component documentation.
If the component redirects to any page, it should be mentioned. If a component triggers an action it should be mentioned. If a component calls an API to fetch some data, the API should be mentioned. Each of these should be links to a dedicated page for that Page/Action/API etc.
In order to explain different components of the page, multiple sub headings may be used. Subheadings for components of the page should start with “Component: ” or somehow indicate this is a page component documentation.
If the component redirects to any page, it should be mentioned. If a component triggers an action it should be mentioned. If a component calls an API to fetch some data, the API should be mentioned. Each of these should be links to a dedicated page for that Page/Action/API etc.
Page State DocumentationTHe page may appear in multiple states depending on who is viewing the page, or what actions they have taken on the page. One sub heading for each state should be defined. Such subheadings should start with “State:” or otherwise indicate this is page state documentation.
If the page is loaded progressively, on initial render there is only partial data, and UI shows a loading state, that UI should be shown as one of the states, and the API that is called to fetch the data should be mentioned in loading state subheading.
THe page may appear in multiple states depending on who is viewing the page, or what actions they have taken on the page. One sub heading for each state should be defined. Such subheadings should start with “State:” or otherwise indicate this is page state documentation.
If the page is loaded progressively, on initial render there is only partial data, and UI shows a loading state, that UI should be shown as one of the states, and the API that is called to fetch the data should be mentioned in loading state subheading.
DataWhen a page is loaded, it loads some data. In some frontend applications, when the page is loaded it only has partial data, and the page is shown in a “loading” state, and further data is fetched on page load and page only ready when that data is loaded.
The initial data should be documented here.
Any API calls on page load should be mentioned in the “Design” section.
When a page is loaded, it loads some data. In some frontend applications, when the page is loaded it only has partial data, and the page is shown in a “loading” state, and further data is fetched on page load and page only ready when that data is loaded.
The initial data should be documented here.
Any API calls on page load should be mentioned in the “Design” section.
