All posts by admin

Software Construction, Software Requirements

How to Quickly Capture and Analyze Requirements for Building a Prototype or Proof of Concept?

Leave a comment
Motivation:

You need to quickly capture and analyze requirements for building a prototype or proof of concept for an enterprise system.

Suggestion:
  1. Capture any artifacts related to a business need. They may be some emails, presentation slides, a proposal document, a legacy system, some similar systems, a feature list or an initial requirement specification.
  2. Define terminologies (terms), build a background and context around the terminologies, expand the terminologies into business roles, business workflows, business components, business entities (objects), and business artifacts as much as possible.
  3. Identify the main stakeholders (roles) who will interact with the system (e.g. Guest, Admin, Developer, User, etc.) and their corresponding business problems or needs (i.e. their motivation of using the software system), and their current business workflows. Create as many scenarios (real world or domain business workflows) as possible. Create a domain model (a model of real world or domain entities, their properties and their relationships) if necessary.
  4. If there is an existing or similar system then identify the core components that each stakeholder will interact with (e.g. Accounts, Profiles, Reporting, APIs, Lessons, Videos, etc.) and their corresponding purposes.
  5. Identify the main tasks that each stakeholder will perform (e.g. Register an Account, Log in System, Create/Edit Profile, Create a Bucket, Generate an API Key, Create/Edit/Delete a Lesson, Create/Edit/Delete a Video, View Bandwidth, etc.).
  6. Identify the inputs and outputs and create mock-ups (sketches) or capture similar screens for each task. The quickest way to create a mock-up is to find similar existing screens in your system or external systems, and modify them. You can also search for templates of similar features in the Internet, and modify them. You can also brainstorm a  new one if you are good at creativity and imagining.
  7. Build or draw a prototype demonstrating 2 or 3 critical end-to-end workflows (An end-to-end workflow is a sequence of tasks that solves a real world problem completely). Contrast a current business workflows with the end-to-end workflows demonstrated by the prototype. The quickest way to create a prototype is to find similar existing workflow of of your system or external systems, and modify them. You can also repurpose a business workflow for a prototype. You can also brainstorm a  new one if you are good at creativity and imagining.
  8. Implement a proof of concept related to the 2 or 3 critical end-to-end workflows.
  9. For a complicated system, you may need to implement a proof of concept, build a prototype, and create a work break down structure or product backlog in parallel to ensure that the requirements are technologically and economically feasible.

 

 

Technologies

How to Convert M4A to WAV File on macOS

Leave a comment

Motivation:

You have downloaded some M4A audio files.

You want to extract convert them to WAV files to listen to them in other devices that do not support playing M4A files.

Procedure:

  • In the Music app on your Mac, choose Music > Preferences, then click Files.
  • Copy the path of Music Media folder location. (An example path is Macintosh HD/Users/admin/Music/Music/Media.)
  • Click the Import Settings… button.
  • In the Import Using pop-up menu, set Import Using = Wav Encoder, then click OK to save the settings.
  • Drag M4A files to the Music app.
  • Select songs in your library, then click File > Convert > Create WAV Version.
  • Go to your library folder (i.e. the Music Media folder location) and copy the WAV files to other devices.
  • Delete the M4A files from your library.
Technologies

How to Move Outlook Data to a New Computer

Leave a comment
Motivation:

You need to move Outlook data and settings from an old computer to a new computer.

Solution:

1. On the destination (new) computer:

    • Type Control Panel in Search box.
    • Click on Control Panel.
    • Select Large icons for View by.
    • Click Mail (32-bit).
    • Click Add. Set Profile Name = Outlook.
    • Follow the instructions to setup an account.

2. On the source (old) computer:

    • Open Outlook.
    • On the File menu, click Data File Management.
    • Click the data file that you want to compact, and then click Settings.
    • Click Compact Now.
    • Close Outlook.

3. Copy and overwrite all the contents of %USERPROFILE%\Local Settings\Application Data\Microsoft\Outlook to the destination computer. Create the Outlook folder if it does not exist.

4. Open Outlook in the destination computer.

Note: If you are using POP3 protocol then all the messages will be re-downloaded again once. If this is true for you then

    • Let Outlook finish downloading the messages, then
    • Click on Unread Mail folder below the Search Folders,
    • Select all the messages,
    • Press Shift, right click and click Delete to permanently delete them all.

 

Operating Systems

How to Remove Caches and Temporary Files in Windows

Leave a comment
Motivation:

You may want to remove caches to update an application status or fix some issues.
You may need to remove temporary files to get some more free disk space.

Solution:

Try clearing files and folders in the directories below.

  • %USERPROFILE%\AppData\Local\Temp
  • C:\Windows\Temp
  • C:\Users\All Users\Package Cache
  • C:\Windows\SoftwareDistribution\Download
  • C:\Windows\Microsoft.NET\Framework\v4.0.30319\Temporary ASP.NET Files

Sometimes you may get permission error when deleting files or folders. If this is true then try the following command before deleting these files and folders.

takeown /f C:\Users\All Users\Package Cache /r /d y
icacls C:\Users\All Users\Package Cache /grant administrators:F /t
Software Construction

How to Quickly and Confidently Read Code?

Leave a comment
Motivation:

You need to read existing source code to add a new feature or fix a bug or clone its features to another language or system.

Suggestion:
  1. Try building and running the code without any modification.
  2. Try building and running the code with your inputs.
  3. Try changing a variable name to meaningful name and make sure that the change does not break anything.
  4. Try changing a package or module name to a meaningful name and make sure that that the change does not break anything.
  5. Try breaking a long method to smaller ones.
  6. Try breaking a large object or file to smaller ones.
  7. Try modifying or adding simple UI elements without touching the business logic or data layer.
  8. Try writing a unit test for a function.
  9. Try replacing an algorithm with with a better one.
  10. Try replacing an old component with a newer or better one.
  11. Try recreating the code structure from the separate components. If you cannot do this then try to understand the architecture of the existing source code.
  12. If you get an error when making the changes above then try showing the error on client side.
  13. If you cannot show the error on client side then try identifying the logic flow of the code related to the error, debug information, and learn about new terminologies or concepts in the code.

Example:

const maskPhone = (val) => {
    const x = val.replace(/\D+/g, '').match(/(\d{0,3})(\d{0,3})(\d{0,4})/);
    return !x[2] ? x[1] : `(${x[1]}) ${x[2]}` + (x[3] ? `-${x[3]}` : ``);
};
export { maskPhone }

If you are not sure about what the JavaScript code above does then try to learn

Another example:

<div class="container">
    <iframe class="responsive-iframe" src="https://www.youtube.com/embed/u9Dg-g7t2l4"></iframe>
</div>
.container {  
    position: relative;  
    overflow: hidden;  
    width: 100%;  
    padding-top: 56.25%; /* 16:9 Aspect Ratio (divide 9 by 16 = 0.5625) */
}
/* Style the iframe to fit in the container div with full height and width */
.responsive-iframe {  
    position: absolute;  
    top: 0;  
    left: 0;  
    bottom: 0;  
    right: 0;  
    width: 100%;  
    height: 100%;
}

If you are not sure about what the HTML and CSS code above  do then try to learn

  • how many ways an element can be placed in a web page (a document),
  • what is the position relationship between an element and its parent,
  • what is the position relationship between an element and its siblings,
  • what is the position relationship between an element and the document root, and
  • what position: relative , position: absolute , overflow: hidden do.

 

 

Software Requirements

Software Requirements Lessons Learned

Leave a comment
Lessons learned 1: Emerging requirements.

Problem: Requirements do not exist. They are emerging and often become incorrect and therefore constant change of requirements happens.

Context: Our goal is to ensure project’ success and client’s satisfaction. In order to achieve this goal our delivered solution must solve our client’s problems and satisfy our client’s needs.

Unfortunately many clients do not know exactly what they want because they want to try a new business process or would like to enhance their current daily business workflow but the new process or workflow has not been defined yet. They would like us to build something for them to try, then if it does not work in real world then they will switch to something else.

The issue becomes even worse when they do not have time to review our prototype and await a quite complete solution.

Sometimes they consider our prototype a complete solution and want us to revise it around their constant changes for production although the architecture limits of the prototype make it very time consuming for such revision or even prevent us from doing such revision. These limits exist because we only build the prototype for the envisioned requirements, not for the endless changes.

Solution:

  • Analysis and communication are critical to ensure that our deliverables match with client’s needs. It does not matter whether we use RUP or Agile process for development. It does not matter whether we use UML, or boxes and lines, or text, or coded prototypes or paper and pen for describing the problems that need to be solved. Our client and analyst must review, refine and confirm problem specification regularly.
  • Otherwise formal requirements should be modeled, reviewed and approved before design phase begins to ensure that our project will deliver solution to the right problems.
Lessons learned 2: Vague requirements.

Problem: Requirements are described vaguely and therefore are implemented incorrectly and many detailed elements are missing.

Context: Our clients just gave us what they have. There could be a video demo of their existing legacy systems, a list of what they wanted, some screenshots captured from other similar systems, a long conversation in an email thread, some phone calls. We just built a solution based on these artifacts and it turned out that our clients had wanted something completely different or many details were missing and not implemented by us.

Solution:

  • Our responsibility is to clarify our client’s problems and needs. Again analysis is an important tool to clarify our client’s problems and needs. Draft requirements can be described in any form, including phone calls, emails, screenshots, video demo, feature list. However all of them should then be refined properly using domain models, workflows, story map, prototypes, use cases, and user interfaces for client to review regularly.
  • Specification by example could help eliminate many unclear aspects when communicating with our client.
  • For requirements of maintenance project, exisiting user interfaces and database schema review are essential for identifying what our client really needs.
  • Sometimes we are stuck at analysis, especially when we analyze integration or enhancement needs that have not existed yet and require creativity. In this case a dirty prototype shoudl be created or proof of concept should be created or small technical exercises  shoudl be done so that we can have inputs for inspiring ideas for analysis.
Lessons learned 3: Requirements dispute.

Problem: Requirements are described only at business level, and therefore many detailed elements are not implemented in the system. However customer does not have time to review the implemented system. When the project is in transition phase it turns out that most of the implemented requirements are non-compliant.

Context: In order to reduce development time and cost many teams just take business requirements and implement them. They may create a work break down structure or a detailed task list for completing these business requirements. However these tasks just describe HOW a business requirement is implemented, NOT WHAT it should be. It means that both USER functional and non-function requirements of a BUSINESS requirement are not analyzed. The situation become bad when it costs too much for a customer to review an implemented business requirement regularly, so the customer just let the teams finish their work. When the project is in the transition phase it turns out that many details of user requirements are not implemented.

Solution:

  • Critical business requirements must be refined into appropriate user stories or use cases.
  • Non-function requirements must be incorporated as notes into each story or use case.
  • Adequate UI sketches (mock-ups) or prototypes or captured screens should be created.
  • Test cases should be created and agreed to validate requirements.
  • A single repository for all requirements should be used for change management and traceability.
  • Architecture and/or proof of concept should be created to discover integration limits of specific requirements.
  • User manual should be created for each business requirement.
  • More importantly, frequent requirements and system validation should be done by a customer if possible to improve the understanding about requirements and prevent communication gaps, especially when an Agile development method is selected to reduce the time and cost. Customer’s assessment must be done regularly (at least weekly, preferred daily if an Agile method is selected), not just once when the project is about to be closed.
Lessons learned 4: Underestimated requirements.

Problem: A requirement is described using one-line description. It may be clear enough for implementation but your team has not built a similar one. Example: Porting a reporting system from R to SQL Server Reporting Services. In the end, it turns out that the effort to implement the requirements is too big due to new programming language learning or the new technology is not suitable for implementing the requirement.

Context: In order to reduce development time and cost many teams just take business requirements and create a rough estimate. The problem is that sometimes there is a lack of experience of a selected technology. Therefore the estimate is incorrect that makes the requirements unable to be implemented within an appropriate budget or using the selected technology.

Solution:

  • Critical business requirements must be refined into appropriate user stories or use cases.
  • Non-function requirements must be incorporated as notes into each story or use case.
  • Adequate UI sketches (mock-ups) or prototypes or captured screens should be created.
  • Test cases should be created and agreed to validate requirements.
  • Proof of concept should be created to discover limits of a selected technology.
Core tools
  • Domain models
  • Business workflows
  • Story maps
  • Requirements analysis
  • Prototypes
  • Use cases
  • User interfaces
  • Specification by example
  • Database schemas
Software Construction

How to Use Git

Leave a comment
Motivation:

You want to use Git to version your files or share your files with other people.

Solution:
  • Register a GitHub or a GitLab account.
  • Create a GitHub repository or a GitLab project.
  • Download and install a Git client.
  • Generate a personal access token.
  • Pull (checkout) a remote repository (e.g. https://github.com/huybien/asp.net-core.git) to an empty local folder (e.g. C:\Users\admin\Downloads\code). 
    git init
git config user.email "[email protected]"
git config user.email
git config user.name "Huy Bien"
git config user.name
git config credential.helper ""
cd C:\Users\admin\Downloads\code
git remote add origin -f https://github.com/huybien/asp.net-core.git
git pull origin main
/ * or * /
git pull origin master
  • Pull (checkout) a remote repository (e.g. https://github.com/huybien/asp.net-core.git) to a local folder that contains existing code (e.g. C:\Users\admin\Downloads\code). 
    cd  C:\Users\admin\Downloads\code
git init --initial-branch=main
git config user.email "[email protected]" git config user.email git config user.name "Huy Bien" git config user.name
git config credential.helper ""
git remote add origin https://github.com/huybien/asp.net-core.git
git fetch --all
git add *.*
git commit -m "new files added"
git push -u origin main
  • Push local files to a remote empty repository. 
    git init
git config user.email "[email protected]"
git config user.email
git config user.name "Huy Bien"
git config user.name
git config credential.helper ""
git add *.*
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/huybien/asp.net-core.git
git push -u origin main
  • Push changes to a remote repository. 
    git config user.email "[email protected]"
git config user.email
git add *.*
git commit -m "CP form"
git branch -M main
git push -u origin main
  • Update (fetch and merge) a local repository. 
    git pull origin main
/* or */
git branch --set-upstream-to=origin/main main
git pull
  • Force updating (fetch and overwrite) the current repository. 
    git fetch --all
git reset --hard origin/main
git clean -fd git pull
  • Force updating (fetch and overwrite) a local repository (e.g. C:\Users\admin\Downloads\code). 
    git -C C:\Users\admin\Downloads\code fetch --all 
git -C C:\Users\admin\Downloads\code reset --hard origin/main 
git -C C:\Users\admin\Downloads\code clean -fd
git -C C:\Users\admin\Downloads\code pull
  • Reset (Revert) a local repository to a previous version. 
    cd C:\Users\admin\Downloads\code
git log --oneline
git reset --hard 4355842
// where 4355842 is a version id.
  • Remove all cached files. 
    git rm -r --cached .
  • Display remote URL. 
    git config --get remote.origin.url

     

 

 

Operating Systems

How to Hide Your IP Location using VPN on Windows 10

Leave a comment

Motivation:

You have VPN credentials and want to hide your IP location for a specific purpose.

Solution:

  • Setup a VPN connection using your VPN credentials.
  • Type and click View network connections in Search box to open the Network Connections window.
  • Right-click the VPN connection and select Properties in the menu.
  • Select the Networking tab.
  • Click the Internet Protocol Version 4 (TCP/IPv4) row, then click the Properties button.
  • Click the Advanced… button.
  • Select Use default gateway on remote network option.

Software Construction

How to Quickly and Reliably Fix a Bug

Leave a comment
Problem:

You need to fix a bug. However it takes you a lot of effort to fix. The fix may also not be reliable. How can you avoid this situation?

Solution:
  1. Try to understand the scenario or use case. Ensure that you and the tester are talking about the same thing and agree about the missing or incorrect elements by comparing the final user interface with the original approved use case or user story or specification.
  2. Try to reliably reproduce the bug. It is okay if this attempt may not be successful.
  3. Try isolating the bug in the same or similar environment by using specific, smaller data and fewer settings. It is okay if this attempt may not be done due to your inherent complex software.
  4. Search for an existing solution using error message generated by the system. Include any library or framework name and version, and operating system name and version in search key words. If there is already an existing solution then this attempt can save us a lot of effort.
  5. Try to understand all the concepts in error message.
  6. Debug and log messages to identify the exact location in the source code that causes the issue. In order to to this we need to do the followings.
    • Identifying the flow of the data, i.e. the use case, the entry point and the exit point in the code related to the issue.
    • Trying to understand programming language syntax in the code. Do not guess anything.
    • Trying to understand purpose, inputs and outputs of library functions related to the use case. Again, do not guess anything.
    • Trying to understand data structure and a part of the database schema related to the use case.
    • Trying to review some concrete values inside the database if possible.
    • Trying to understand concepts, algorithms and architecture related to the use case. Again, do not guess anything.
    • These steps may be done in parallel and iteratively.
  7. Guess a cause of the problem based on the information that you can get in the sixth step.
  8. Try to isolate the issue, i.e. try to reproduce the issue using specific code and unit tests, if possible.
  9. Search for or propose a solution for the cause, i.e. propose a fix.
  10. Implement and test the fix.
  11. Repeat from step 5 to step 10 if necessary.

 

Web Application Development

How to Fix a Hacked WordPress Website

Leave a comment
Problem:

When you visit your WordPress website you are randomly redirected to unwanted websites.

Verification:
  • Log in your website as an Administrator.
  • Go to Appearance >> Theme File Editor.
  • Click on the Theme Functions link on the right side.
  • Verify if malicious code was injected into the functions.php file. Example of malicious code: 
    <?php @ini_set('display_errors', '0'); 
error_reporting(0); 
global $zeeta;
  • Download the wp-config.php file to your machine via FTP or SSH.
  • Verify if malicious code was injected into the wp-config.php file. Example of malicious code: 
    include_once(ABSPATH . WPINC . '/header.php');
Solution:
  • Stop the website.
  • Download the whole website to your local machine. 
    cd /var/hosting/huybien.com
ls
sudo zip -r huybien.zip /var/hosting/huybien.com/html
Configuration:
  • Log in your website as an Administrator.
  • Change your Administrator’s password.
  • Change file owner and group to www-data: 
    sudo chown -R www-data:www-data /var/hosting/huybien.com/html
  • IMPORTANT STEP – Set minimum permissions for folders and files: 
    cd /var/hosting/huybien.com/html
sudo find . -type d -exec chmod 755 {} \; # directory permissions rwxr-xr-x
sudo find . -type f -exec chmod 644 {} \; # file permissions rw-r--r--
  • Remove all the unused plug-ins or themes.
  • Install, activate and configure a CAPTCHA plug-in to protect Login Form, Registration Form, Lost Password Form, Reset Password Form and Comment Form if there is no one.
  • Disable insecure FTP access if there is one.
  • Install and activate the Simple History plugin to review access to your website. After 1 or 2 days, review the access information, and possibly block the malicious IP addresses using the Windows Firewall.
  • Install, activate and configure Cerber Security plug-in to automatically detect and block the malicious IP addresses.
  • Back up database. 
    cd /home/ubuntu
ls
mysqldump -u root -p -h localhost huybiencomwp > huybiencomwp.sql
  • Back up files. 
    cd /home/ubuntu
ls
sudo zip -r /home/ubuntu/huybien.zip /var/hosting/huybien.com/html
  • Download database and files backup.
  • Remove the backups. 
    sudo rm -rf /home/ubuntu/huybiencomwp.sql
sudo rm -rf /home/ubuntu/huybien.zip
ls