none
What are the best practices for adding descriptions to custom fields? RRS feed

  • Question

  • Does anyone has proven best practices on how to write descriptions for custom fields? 

    Since the descriptions appear every time a custom field is used, they can be very repetitive and make the screen look busy. If someone could point me in the right direction, I will appreciate it. 


    Monday, February 25, 2019 10:11 PM

Answers

  • Hello,

    I always make these short and concise with enough details so the users knows what information is required - this will vary based on the organisations requirements / process and users.

    Paul


    Paul Mather | Twitter | http://pwmather.wordpress.com | CPS | MVP | Downloads

    Tuesday, February 26, 2019 9:40 AM
    Moderator
  • Thank you, Paul. Good points. Descriptions for custom fields can be tricky. As a developer, you don't know the lingo in an organisation. Hence, you might write something entirely off-base. I think that as a guideline I would suggest the following

    1) Only write descriptions when a custom field is ambiguous.  For example, if you ask for "Birthday", you don't need to expand on it. But If you ask for "Budget Allocation", you might want to describe a little bit of what's expected. If you ask for "Cost", you might want to say, "Cost includes applicable taxes and delivery charges" for example.

    2) Custom field descriptions may appear in as many PDPs as they are required. So, make them short - if possible in one single sentence. Spell-check, avoid acronyms and don't use links.

    3) Don't ask for the obvious input. If a custom field is a dropdown, don't ask for "Select from the dropdown the budget allocation". Instead, try to describe the purpose of the budget allocation so an informed choice can be selected. 

    4) There is always end-user documentation. A description should not replace end-user documentation where all the fields are explained in detailed. 

    5) run them by the SME. Once you have done your best, export the list of custom fields descriptions and present them to the SME. They may expand, or remove descriptions - use OData in EXCEL to extract the full list and descriptions (.../sites/pwa/_api/ProjectServer/CustomFields)

    6) While performing UAT, review with users that have never seen the form before. Take note of what questions they have and decide if the description should be updated or include more details in the end-user documentation.

    Let me know if there are any other suggestions. 




    Tuesday, February 26, 2019 4:36 PM
  • All good points Jose. 

    For task level ECFs, the descriptions aren't shown so I never use them.


    Ben Howard [MVP] | web | blog | book | downloads | P2O

    Wednesday, February 27, 2019 8:38 AM
    Moderator

All replies

  • Hello,

    I always make these short and concise with enough details so the users knows what information is required - this will vary based on the organisations requirements / process and users.

    Paul


    Paul Mather | Twitter | http://pwmather.wordpress.com | CPS | MVP | Downloads

    Tuesday, February 26, 2019 9:40 AM
    Moderator
  • Thank you, Paul. Good points. Descriptions for custom fields can be tricky. As a developer, you don't know the lingo in an organisation. Hence, you might write something entirely off-base. I think that as a guideline I would suggest the following

    1) Only write descriptions when a custom field is ambiguous.  For example, if you ask for "Birthday", you don't need to expand on it. But If you ask for "Budget Allocation", you might want to describe a little bit of what's expected. If you ask for "Cost", you might want to say, "Cost includes applicable taxes and delivery charges" for example.

    2) Custom field descriptions may appear in as many PDPs as they are required. So, make them short - if possible in one single sentence. Spell-check, avoid acronyms and don't use links.

    3) Don't ask for the obvious input. If a custom field is a dropdown, don't ask for "Select from the dropdown the budget allocation". Instead, try to describe the purpose of the budget allocation so an informed choice can be selected. 

    4) There is always end-user documentation. A description should not replace end-user documentation where all the fields are explained in detailed. 

    5) run them by the SME. Once you have done your best, export the list of custom fields descriptions and present them to the SME. They may expand, or remove descriptions - use OData in EXCEL to extract the full list and descriptions (.../sites/pwa/_api/ProjectServer/CustomFields)

    6) While performing UAT, review with users that have never seen the form before. Take note of what questions they have and decide if the description should be updated or include more details in the end-user documentation.

    Let me know if there are any other suggestions. 




    Tuesday, February 26, 2019 4:36 PM
  • All good points Jose. 

    For task level ECFs, the descriptions aren't shown so I never use them.


    Ben Howard [MVP] | web | blog | book | downloads | P2O

    Wednesday, February 27, 2019 8:38 AM
    Moderator
  • Good point.  It is very annoying that internal special fields like Owner, Project Name, Project ID don't have descriptions. Or am I wrong?
    Thursday, February 28, 2019 4:48 AM
  • They don't have descriptions, but then they are self describing I would say.

    Ben Howard [MVP] | web | blog | book | downloads | P2O

    Thursday, February 28, 2019 8:39 AM
    Moderator